<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.10">
<meta name="author" content="Dan Allen, Sarah White">
<title>How do I convert a document?</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment @import statement to use as custom stylesheet */
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}
audio,video{display:inline-block}
audio:not([controls]){display:none;height:0}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite::before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
:not(pre)>code.nobreak{word-wrap:normal}
:not(pre)>code.nowrap{white-space:nowrap}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre>code{display:block}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em}
pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em}
pre.pygments .lineno::before{content:"";margin-right:-.125em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
table.tableblock{max-width:100%;border-collapse:separate}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
td.tableblock>.content>:last-child.sidebarblock{margin-bottom:0}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot,table.frame-ends{border-width:1px 0}
table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
ul.checklist{margin-left:.625em}
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>How do I convert a document?</h1>
<div class="details">
<span id="author" class="author">Dan Allen</span><br>
<span id="author2" class="author">Sarah White</span><br>
</div>
<div id="toc" class="toc2">
<div id="toctitle">目录</div>
<ul class="sectlevel1">
<li><a href="#_selecting_an_output_format">Selecting an Output Format</a></li>
<li><a href="#_converting_a_document_to_html">Converting a document to HTML</a>
<ul class="sectlevel2">
<li><a href="#_using_the_command_line_tool">Using the command line tool</a></li>
<li><a href="#_using_the_ruby_api">Using the Ruby API</a></li>
<li><a href="#_styling_the_html_with_css">Styling the HTML with CSS</a></li>
<li><a href="#_managing_images">Managing images</a></li>
<li><a href="#_coderay_and_pygments_stylesheets">CodeRay and Pygments stylesheets</a></li>
</ul>
</li>
<li><a href="#_converting_a_document_to_docbook">Converting a document to DocBook</a></li>
<li><a href="#_resources_and_help">Resources and help</a></li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This guide introduces the Asciidoctor processor and the output formats it produces.
You will learn how to:</p>
</div>
<div class="ulist checklist">
<ul class="checklist">
<li>
<p><i class="fa fa-check-square-o"></i> process a document from the CLI and API</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> convert a document to HTML</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> apply the default Asciidoctor CSS theme</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> convert a document to DocBook 5</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
In order to convert your document, you&#8217;ll need to have Asciidoctor installed.
For step-by-step installation instructions, read the <a href="https://asciidoctor.org/docs/install-toolchain">Installing the Toolchain</a> guide.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>While the AsciiDoc syntax is designed to be readable in raw form, the intended audience for that format are writers and editors.
Readers aren&#8217;t going to appreciate the raw text nearly as much.
Aesthetics matter.
You&#8217;ll want to apply nice typography with font sizes that adhere to the golden ratio, colors, icons and images to give it the respect it deserves.
That&#8217;s where converters, backends, and themes come into play.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_selecting_an_output_format">Selecting an Output Format</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The Asciidoctor processor is typically used to parse an AsciiDoc document and convert it to a variety of formats, such as HTML, DocBook, or PDF.
This section describes how to specify the output format.</p>
</div>
<div class="paragraph">
<p>The processor generates the output format using a converter.
Each converter is mapped to the name of a backend.
You specify the backend&#8212;&#8203;and, in turn, the converter&#8212;&#8203;using the <code>-b</code> (<code>--backend</code>) command line option or <code>backend</code> API option.
If no backend is specified, the processor uses the converter for the default backend (<code>html5</code>).</p>
</div>
<div class="paragraph">
<p>Asciidoctor provides several built-in converters, which are mapped to the following backend names:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">html (or html5)</dt>
<dd>
<p>HTML 5, styled with CSS3 (default).</p>
</dd>
<dt class="hdlist1">xhtml (or xhtml5)</dt>
<dd>
<p>The XHTML variant of the output from <code>html5</code>.</p>
</dd>
<dt class="hdlist1">docbook (or docbook5)</dt>
<dd>
<p>DocBook 5.0 XML.</p>
</dd>
<dt class="hdlist1">manpage</dt>
<dd>
<p>Manual pages for Unix and Unix-like operating systems.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Asciidoctor also has several add-on converters, which can be plugged in by adding the appropriate library to the runtime path (e.g., <code>-r asciidoctor-pdf</code>).
These converters are mapped to the following backend names:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">pdf</dt>
<dd>
<p>PDF, a portable document format.
Requires the <a href="https://rubygems.org/gems/asciidoctor-pdf">asciidoctor-pdf</a> gem.</p>
</dd>
<dt class="hdlist1">epub3</dt>
<dd>
<p>EPUB3, a distribution and interchange format standard for digital publications and documents.
Requires the <a href="https://rubygems.org/gems/asciidoctor-epub3">asciidoctor-epub3</a> gem.</p>
</dd>
<dt class="hdlist1">latex</dt>
<dd>
<p>LaTeX, a document preparation system for high-quality typesetting.
Requires the <a href="https://rubygems.org/gems/asciidoctor-latex">asciidoctor-latex</a> gem.</p>
</dd>
<dt class="hdlist1">mallard</dt>
<dd>
<p>Mallard 1.0 XML.
Requires the <a href="https://github.com/asciidoctor/asciidoctor-mallard">asciidoctor-mallard</a> gem (not yet released).</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>There are also converters available for HTML5 presentation systems such as reveal.js and Bespoke.js.
Those converters are still in development and will be documented once releases become available.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_converting_a_document_to_html">Converting a document to HTML</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Asciidoctor&#8217;s default output is HTML.
You can convert a document to HTML using the CLI or the Ruby API.</p>
</div>
<div class="sect2">
<h3 id="_using_the_command_line_tool">Using the command line tool</h3>
<div class="paragraph">
<p>In this section, we&#8217;ll create a sample document, then process and convert it with Asciidoctor&#8217;s <code>html5</code> converter.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Create an AsciiDoc file like the one below</p>
</li>
<li>
<p>Save the file as <em class="path">mysample.adoc</em></p>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>= My First Experience with the Dangers of Documentation

In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.

== Origins

You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.</code></pre>
</div>
</div>
<div class="paragraph">
<p>To convert <em class="path">mysample.adoc</em> to HTML from the command line:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Open a console</p>
</li>
<li>
<p>Switch to the directory that contains the <em class="path">mysample.adoc</em> document</p>
</li>
<li>
<p>Call the Asciidoctor processor with the <code>asciidoctor</code> command, followed by the name of the document you want to convert</p>
</li>
</ol>
</div>
<div class="literalblock">
<div class="content">
<pre>$ asciidoctor mysample.adoc</pre>
</div>
</div>
<div class="paragraph">
<p>Remember, Asciidoctor&#8217;s default converter is html5, so it isn&#8217;t necessary to specify it with the <code>-b</code> command.</p>
</div>
<div class="paragraph">
<p>You won&#8217;t see any messages printed to the console.
If you type <code>ls</code> or view the directory in a file manager, there is a new file named <em class="path">mysample.html</em>.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ ls
mysample.adoc  mysample.html</pre>
</div>
</div>
<div class="paragraph">
<p>Asciidoctor derives the name of the output document from the name of the input document.</p>
</div>
<div class="paragraph">
<p>Open <em class="path">mysample.html</em> in your web browser.
Your document should look like the image below.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="imageblock">
<div class="content">
<img src="https://d33wubrfki0l68.cloudfront.net/1a0ac05789e93089b59c4572cf704f9580e2b1ea/dcd6a/images/mysample.png" alt="mysample">
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The document&#8217;s text, titles, and link is styled by the default Asciidoctor stylesheet, which is embedded in the HTML output.
As a result, you could save <em class="path">mysample.html</em> to any computer and it will look the same.</p>
</div>
</div>
<div class="sect2">
<h3 id="_using_the_ruby_api">Using the Ruby API</h3>
<div class="paragraph">
<p>Asciidoctor also includes a Ruby API that lets you generate an HTML document directly from a Ruby application.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="ruby">require <span class="string"><span class="delimiter">'</span><span class="content">asciidoctor</span><span class="delimiter">'</span></span>

<span class="constant">Asciidoctor</span>.convert_file <span class="string"><span class="delimiter">'</span><span class="content">mysample.adoc</span><span class="delimiter">'</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Alternatively, you can capture the HTML output in a variable instead of writing it to a file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="ruby">html = <span class="constant">Asciidoctor</span>.convert_file <span class="string"><span class="delimiter">'</span><span class="content">mysample.adoc</span><span class="delimiter">'</span></span>, <span class="key">to_file</span>: <span class="predefined-constant">false</span>, <span class="key">header_footer</span>: <span class="predefined-constant">true</span>
puts html</code></pre>
</div>
</div>
<div class="paragraph">
<p>The convert methods also accept a map of options.
Use of this map is described in <a href="user-manual.html#ruby-api-options">Ruby API Options</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_styling_the_html_with_css">Styling the HTML with CSS</h3>
<div class="paragraph">
<p>Asciidoctor uses CSS for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes.
It comes bundled with a stylesheet, named <em class="path">asciidoctor.css</em>.
When you generate a document with the <code>html5</code> backend, the <em class="path">asciidoctor.css</em> stylesheet is embedded into the HTML output by default (when the safe mode is less than <code>SECURE</code>).</p>
</div>
<div class="paragraph">
<p>You have the option of linking to the stylesheet instead of embedding it.
This is the mandatory behavior when the safe mode is SECURE.
If your stylesheet is being linked when you expect it to be embedded, lower the safe mode (<code>safe</code> is the recommend value).</p>
</div>
<div class="paragraph">
<p>To have your document link to the stylesheet, set the <code>linkcss</code> attribute in the document&#8217;s header.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>= My First Experience with the Dangers of Documentation
:linkcss:

In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.

== Origins

You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can also set linkcss with the CLI.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ asciidoctor -a linkcss mysample.adoc</pre>
</div>
</div>
<div class="paragraph">
<p>Now, when you view the directory, you should see the file <em class="path">asciidoctor.css</em> in addition to <em class="path">mysample.adoc</em> and <em class="path">mysample.html</em>.
The linkcss attribute automatically copies asciidoctor.css to the output directory.
Additionally, you can inspect <em class="path">mysample.html</em> in your browser and see <code>&lt;link rel="stylesheet" href="./asciidoctor.css"&gt;</code> inside the <code>&lt;head&gt;</code> tags.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="imageblock">
<div class="content">
<img src="https://d33wubrfki0l68.cloudfront.net/03c269d112e662b7434cb73f191c5e0c1ba0039f/8d9ca/images/mysample-link.png" alt="mysample link">
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>If you don&#8217;t want any styles applied to the HTML output of your document, unset the <code>stylesheet</code> attribute.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ asciidoctor -a stylesheet! mysample.adoc</pre>
</div>
</div>
<div class="paragraph">
<p>One of Asciidoctor&#8217;s strengths is the ease in which you can swap the default stylesheet for an <a href="user-manual.html#stylesheet-factory">alternative Asciidoctor theme</a> or use your own <a href="user-manual.html#applying-a-theme">custom stylesheet</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_managing_images">Managing images</h3>
<div class="paragraph">
<p>Images are not embedded in the HTML output by default.
If you have image references in your document, you&#8217;ll have to save the image files in the same directory as your converted document.</p>
</div>
<div class="paragraph">
<p>As an alternative, you can embed the images directly into the document by setting the <code>data-uri</code> document attribute.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ asciidoctor -a data-uri mysample.adoc</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="asciidoc">= My First Experience with the Dangers of Documentation
:imagesdir: myimages
:data-uri:

In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.

== Origins

[.left.text-center]
image::wolpertinger.jpg[Wolpertinger]

You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.</code></pre>
</div>
</div>
<div class="exampleblock">
<div class="content">
<div class="imageblock">
<div class="content">
<img src="https://d33wubrfki0l68.cloudfront.net/342307762e852b15f190c374da900a7977f046bd/004c4/images/mysample-data-uri.png" alt="mysample data uri">
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>If the target of one or more images in the document is a URI, you must also set the <code>allow-uri-read</code> attribute securely and run Asciidoctor in <code>SECURE</code> mode or less.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ asciidoctor -a data-uri -a allow-uri-read mysample.adoc</pre>
</div>
</div>
<div class="paragraph">
<p>The same is true when converting the document to PDF using Asciidoctor PDF, even if the <code>allow-uri-read</code> attribute is not set (since the behavior is implied).</p>
</div>
</div>
<div class="sect2">
<h3 id="_coderay_and_pygments_stylesheets">CodeRay and Pygments stylesheets</h3>
<div class="paragraph">
<p>Asciidoctor will also embed the theme stylesheet for the CodeRay or Pygments syntax highlighter.</p>
</div>
<div class="paragraph">
<div class="title">CodeRay</div>
<p>If the <code>source-highlighter</code> attribute is <code>coderay</code> and the <code>coderay-css</code> attribute is <code>class</code>, the CodeRay stylesheet is:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>embedded</em> by default</p>
</li>
<li>
<p><em>copied</em> to the file <em class="path">asciidoctor-coderay.css</em> inside the <code>stylesdir</code> folder within the output directory if <code>linkcss</code> is set</p>
</li>
</ul>
</div>
<div class="paragraph">
<div class="title">Pygments</div>
<p>If the <code>source-highlighter</code> attribute is <code>pygments</code> and the <code>pygments-css</code> attribute is <code>class</code>, the Pygments stylesheet is:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>embedded</em> by default</p>
</li>
<li>
<p><em>copied</em> to the file <em class="path">asciidoctor-pygments.css</em> inside the <code>stylesdir</code> folder within the output directory if <code>linkcss</code> is set</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_converting_a_document_to_docbook">Converting a document to DocBook</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Asciidoctor can produce DocBook 5.0 output.
Since the AsciiDoc syntax was designed with DocBook output in mind, the conversion is very good.
There&#8217;s a corresponding DocBook element for each markup in the AsciiDoc syntax.</p>
</div>
<div class="paragraph">
<p>To convert the <code>mysample.adoc</code> document to DocBook 5.0 format, call the processor with the backend flag set to <code>docbook</code>.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ asciidoctor -b docbook mysample.adoc</pre>
</div>
</div>
<div class="paragraph">
<p>A new XML document, named <code>mysample.xml</code>, will now be present in the current directory.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ ls
mysample.adoc  mysample.html  mysample.xml</pre>
</div>
</div>
<div class="paragraph">
<p>Here&#8217;s a snippet of the XML generated by the DocBook converter.</p>
</div>
<div class="listingblock">
<div class="title">XML generated from AsciiDoc</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="tag">&lt;article</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://docbook.org/ns/docbook</span><span class="delimiter">&quot;</span></span>
    <span class="attribute-name">xmlns:xl</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://www.w3.org/1999/xlink</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">version</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5.0</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">xml:lang</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  <span class="tag">&lt;info&gt;</span>
    <span class="tag">&lt;title&gt;</span>Hello, AsciiDoc!<span class="tag">&lt;/title&gt;</span>
    <span class="tag">&lt;date&gt;</span>2013-09-03<span class="tag">&lt;/date&gt;</span>
    <span class="tag">&lt;author&gt;</span>
      <span class="tag">&lt;personname&gt;</span>
        <span class="tag">&lt;firstname&gt;</span>Doc<span class="tag">&lt;/firstname&gt;</span>
        <span class="tag">&lt;surname&gt;</span>Writer<span class="tag">&lt;/surname&gt;</span>
      <span class="tag">&lt;/personname&gt;</span>
      <span class="tag">&lt;email&gt;</span>doc@example.com<span class="tag">&lt;/email&gt;</span>
    <span class="tag">&lt;/author&gt;</span>
    <span class="tag">&lt;authorinitials&gt;</span>DW<span class="tag">&lt;/authorinitials&gt;</span>
  <span class="tag">&lt;/info&gt;</span>
  <span class="tag">&lt;simpara&gt;</span>
    An introduction to <span class="tag">&lt;link</span> <span class="attribute-name">xl:href</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://asciidoc.org</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>AsciiDoc<span class="tag">&lt;/link&gt;</span>.
  <span class="tag">&lt;/simpara&gt;</span>
  <span class="tag">&lt;section</span> <span class="attribute-name">xml:id</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">_first_section</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;title&gt;</span>First Section<span class="tag">&lt;/title&gt;</span>
    <span class="tag">&lt;itemizedlist&gt;</span>
      <span class="tag">&lt;listitem&gt;</span>
        <span class="tag">&lt;simpara&gt;</span>item 1<span class="tag">&lt;/simpara&gt;</span>
      <span class="tag">&lt;/listitem&gt;</span>
      <span class="tag">&lt;listitem&gt;</span>
        <span class="tag">&lt;simpara&gt;</span>item 2<span class="tag">&lt;/simpara&gt;</span>
      <span class="tag">&lt;/listitem&gt;</span>
    <span class="tag">&lt;/itemizedlist&gt;</span>
  <span class="tag">&lt;/section&gt;</span>
<span class="tag">&lt;/article&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If you&#8217;re on Linux, you can view the DocBook file with <a href="https://wiki.gnome.org/action/show/Apps/Yelp">Yelp</a>.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ yelp mysample.xml</pre>
</div>
</div>
<div class="paragraph">
<p>And of course, if you&#8217;re using the Asciidoctor Ruby API, you can generate a DocBook document directly from your application.</p>
</div>
<div class="listingblock">
<div class="title">Generate DocBook output from the API</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="ruby"><span class="constant">Asciidoctor</span>.convert_file <span class="string"><span class="delimiter">'</span><span class="content">mysample.adoc</span><span class="delimiter">'</span></span>, <span class="key">backend</span>: <span class="string"><span class="delimiter">'</span><span class="content">docbook</span><span class="delimiter">'</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>By default, the docbook converter produces DocBook 5.0 output that is compliant to the DocBook 5.0 specification.</p>
</div>
<div class="paragraph">
<p>A summary of the differences are as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>XSD declarations are used on the document root instead of a DTD</p>
</li>
<li>
<p><code>&lt;info&gt;</code> elements for document info instead of <code>&lt;articleinfo&gt;</code> and <code>&lt;bookinfo&gt;</code></p>
</li>
<li>
<p>elements that hold the author&#8217;s name are wrapped in a <code>&lt;personname&gt;</code> element</p>
</li>
<li>
<p>the id for an element is defined using an <code>xml:id</code> attribute</p>
</li>
<li>
<p><code>&lt;link&gt;</code> is used for links instead of <code>&lt;ulink&gt;</code></p>
</li>
<li>
<p>the URL for a link is defined using the <code>xl:href</code> attribute</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Refer to <a href="https://tdg.docbook.org/tdg/5.0/ch01.html#introduction-whats-new">What&#8217;s new in DocBook v5.0?</a> for more details about how DocBook 5.0 differs from DocBook 4.5.</p>
</div>
<div class="paragraph">
<p>If you need to output DocBook 4.5, you may find the community-supported <a href="https://github.com/asciidoctor/asciidoctor-docbook45">DocBook 4.5 Converter</a> useful.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ asciidoctor -b docbook45 mysample.adoc</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_resources_and_help">Resources and help</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There&#8217;s really no end to the customization you can apply to the output that the Asciidoctor processor generates.
We&#8217;ve just scratched the surface in this guide.</p>
</div>
<div class="paragraph">
<p>To learn about the other backends and stylesheets, checkout out the following resources:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="http://themes.asciidoctor.org/">The Asciidoctor Stylesheet Factory showcase</a></p>
</li>
<li>
<p><a href="https://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/">Create and use a custom theme</a></p>
</li>
<li>
<p><a href="user-manual.html#man-pages">Create and convert a man page</a></p>
</li>
<li>
<p>Convert a document to PDF with the <a href="https://github.com/asciidoctor/asciidoctor-fopub/blob/master/README.adoc">asciidoctor-fopub tool</a></p>
</li>
<li>
<p><a href="https://github.com/asciidoctor/asciidoctor-backends">Asciidoctor&#8217;s backend repository</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Need an overview of the AsciiDoc syntax?</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://asciidoctor.org/docs/asciidoc-syntax-quick-reference">AsciiDoc Quick Reference</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Want to dive deep into all of Asciidoctor&#8217;s features?</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://asciidoctor.org/docs/user-manual">Asciidoctor User&#8217;s Manual</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Additional guides are listed on the <a href="https://asciidoctor.org/docs">Documentation</a> page.
Also, don&#8217;t forget to join the <a href="https://discuss.asciidoctor.org">Asciidoctor mailing list</a>, where you can ask questions and leave comments.</p>
</div>
</div>
</div>
</div>
<style>
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
pre.CodeRay{background:#f7f7f8}
.CodeRay .line-numbers{border-right:1px solid currentColor;opacity:.35;padding:0 .5em 0 0}
.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
.CodeRay .line-numbers strong{color:#000}
table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.CodeRay td{vertical-align:top;line-height:inherit}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.code{padding:0 0 0 .75em}
.CodeRay .debug{color:#fff !important;background:#000080 !important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:#000080}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:#008080}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:#008080}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:#008080}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
</body>
</html>